feat: implement OSSFS storage backend in sandbox lifecycle by hittyt · Pull Request #340 · alibaba/OpenSandbox

hittyt · 2026-03-04T11:00:21Z

This PR implements the OSSFS storage backend for the sandbox lifecycle, as detailed in OSEP-0003.

Key features:

Docker Runtime Integration: Implemented mount management with reference counting and on-demand ossfs mounting.
Enhanced Validation: Added rigorous checks for OSS buckets, endpoints, and credentials.
Automatic Cleanup: Ensures OSSFS paths are unmounted when the last dependent sandbox is deleted.

oseps/0003-volume-and-volumebinding-support.md

jwx0925 · 2026-03-04T12:50:35Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a72893a549

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

server/src/services/docker.py

chatgpt-codex-connector · 2026-03-04T12:54:42Z

server/src/services/docker.py

+            current = self._ossfs_mount_ref_counts.get(mount_key, 0)
+            if current <= 1:
+                self._ossfs_mount_ref_counts.pop(mount_key, None)
+                should_unmount = True


Unmount only when OSSFS mount has tracked references

The release logic treats current == 0 the same as current == 1 and proceeds to unmount. After process restart, _ossfs_mount_ref_counts is empty (it is initialized in-memory and not rebuilt from existing containers), so deleting one sandbox can unmount a shared OSSFS path still used by other running sandboxes. This can break active workloads by tearing down their underlying bind source unexpectedly.

Useful? React with 👍 / 👎.

Pangjiping · 2026-03-04T13:25:30Z

Please rebase main to resolve pyproject.toml format error

- Implement OSSFS volume support in Docker runtime with mount reference counting. - Add comprehensive validation and unit tests for the new storage backend.

sdks/sandbox/python/src/opensandbox/api/lifecycle/models/credential_ref.py

Pangjiping · 2026-03-07T02:54:16Z

server/src/services/docker.py

        return pvc_inspect_cache

+    @staticmethod
+    def _derive_oss_region(endpoint: str) -> Optional[str]:


What is the purpose of resolving the region? It looks like the region is only required for ossfs 1.0 with sigv4 enabled, and it is not the region of the OSS bucket, but rather the region of client.

reference: https://help.aliyun.com/zh/oss/developer-reference/advanced-configurations?spm=a2c4g.11186623.help-menu-31815.d_1_2_7_2.5fe6686exm5Yta

region=cn-hangzhou：OSS Bucket请求地域标识符，挂载时添加-oregion=<region_id>，默认为空。在使用V4签名时必须添加该选项来作为发起请求地域的标识符。

As the oss doc described, sigv4 is ONLY used for version 1.0 mode, and the purpose of this function is prepare the region field for ossv1 command construction.

But region is the region of client，not region of oss bucket

Removed region logic

server/src/services/docker.py

server/src/services/validators.py

server/src/services/docker.py

server/src/services/validators.py

…vior Move Docker OSSFS-specific logic into a dedicated module to reduce branching noise in the core provisioning flow, and align OSSFS request validation with schema-driven constraints and platform support boundaries. This also fixes server pyproject TOML parsing so validation/test tooling can run reliably. Made-with: Cursor

Make OSSFS mount preparation transactional by rolling back already prepared mount keys when a later mount in the same batch fails. Add a regression test to prevent ref-count leaks in multi-volume partial-failure scenarios. Made-with: Cursor

Remove endpoint-derived region/sigv4 auto-injection for OSSFS 1.0 so region semantics stay explicitly controlled by caller options. Add assertions to keep v1 command generation free of implicit region flags. Made-with: Cursor

Install and expose both JDK 8 and JDK 17 in Java E2E so Gradle toolchain resolution does not depend on foojay auto-download in CI. Configure Gradle installation paths explicitly to avoid intermittent Java 8 provisioning failures. Made-with: Cursor

jwx0925 · 2026-03-11T01:46:46Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8338c4d7cb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-03-11T01:54:12Z

server/src/services/docker.py

        mem_limit, nano_cpus = self._resolve_resource_limits(request)

+        # Prepare OSSFS mounts first so binds can reference mounted host paths.
+        ossfs_mount_keys = self._prepare_ossfs_mounts(request.volumes)


Release OSSFS mounts on sidecar provisioning failures

OSSFS mounts are prepared before sidecar setup, but mount cleanup is only in the later try/except around _create_and_start_container. If provisioning fails earlier (for example _start_egress_sidecar or another pre-container step raises), the function exits without calling _release_ossfs_mounts, leaving stale ref counts and mounted paths for a sandbox that was never created.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-03-11T01:54:12Z

server/src/services/docker.py

+        with self._ossfs_mount_lock:
+            self._ossfs_mount_ref_counts = restored_mount_refs


Initialize OSSFS refs before expiring restored sandboxes

On startup, _restore_existing_sandboxes can call _expire_sandbox for already-expired containers before _ossfs_mount_ref_counts is assigned. Because _expire_sandbox now releases mounts through ref counts, those keys are treated as untracked and skipped, so mounts from expired containers can remain mounted after restart instead of being cleaned up.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-03-11T01:54:12Z

server/src/services/docker.py

+        mount_keys_raw = labels.get(SANDBOX_OSSFS_MOUNTS_LABEL, "[]")
+        try:
+            mount_keys: list[str] = json.loads(mount_keys_raw)
+        except (TypeError, json.JSONDecodeError):


Reject user-controlled OSSFS mount labels during teardown

Teardown parses opensandbox.io/ossfs-mounts directly from container labels and releases those mount keys. Since metadata is copied into labels and this internal key is not reserved, a client can forge this label value and trigger ref-count decrements/unmounts for mounts used by other sandboxes when this sandbox is deleted or cleaned up.

Useful? React with 👍 / 👎.

hittyt requested review from Generalwin, Pangjiping, Spground, fengcone, jwx0925, kevinlynx and ninan-nn as code owners March 4, 2026 11:00

Pangjiping reviewed Mar 4, 2026

View reviewed changes

oseps/0003-volume-and-volumebinding-support.md Outdated Show resolved Hide resolved

chatgpt-codex-connector bot reviewed Mar 4, 2026

View reviewed changes

hittyt force-pushed the feat/support-ossfs-api branch from a72893a to ce216ac Compare March 4, 2026 13:17

feat: implement OSSFS storage backend in sandbox lifecycle

c12516d

- Implement OSSFS volume support in Docker runtime with mount reference counting. - Add comprehensive validation and unit tests for the new storage backend.

hittyt force-pushed the feat/support-ossfs-api branch from ce216ac to c12516d Compare March 4, 2026 13:27

Pangjiping added feature New feature or request component/server labels Mar 5, 2026

hittyt added 3 commits March 5, 2026 13:09

feat: add js sdk model and examples

8354bdc

fix: windows test failure

5c2ab9d

chore: improve example doc

25eb4ed

hittyt force-pushed the feat/support-ossfs-api branch from aaf4e73 to 25eb4ed Compare March 5, 2026 05:32

hittyt added 2 commits March 5, 2026 14:01

refactor: remove useless ossfs.path

67eb04a

feat: implement version-specific OSSFS mount and simplify credentials

f93f2a8

Pangjiping requested changes Mar 7, 2026

View reviewed changes

Pangjiping assigned Pangjiping and ninan-nn Mar 7, 2026

hittyt requested a review from Pangjiping March 8, 2026 06:16

hittyt force-pushed the feat/support-ossfs-api branch from a332819 to 288e383 Compare March 8, 2026 06:53

fix(server): avoid implicit region injection for ossfs v1

e6847f9

Remove endpoint-derived region/sigv4 auto-injection for OSSFS 1.0 so region semantics stay explicitly controlled by caller options. Add assertions to keep v1 command generation free of implicit region flags. Made-with: Cursor

hittyt force-pushed the feat/support-ossfs-api branch from 11e4b44 to 8338c4d Compare March 9, 2026 13:57

chatgpt-codex-connector bot reviewed Mar 11, 2026

View reviewed changes

		with self._ossfs_mount_lock:
		self._ossfs_mount_ref_counts = restored_mount_refs

Conversation

hittyt commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

jwx0925 commented Mar 4, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector bot Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

hittyt Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Pangjiping commented Mar 4, 2026

Uh oh!

Uh oh!

Pangjiping Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

hittyt Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

Pangjiping Mar 8, 2026

Choose a reason for hiding this comment

Uh oh!

hittyt Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jwx0925 commented Mar 11, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hittyt commented Mar 4, 2026 •

edited

Loading